home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / tools / jade / src / regexp / regexp.man < prev    next >
Text File  |  1995-03-09  |  8KB  |  265 lines
  1.  
  2.  
  3.  
  4. REGEXP(3)              C LIBRARY FUNCTIONS              REGEXP(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      regcomp, regexec,  regsub,  regerror  -  regular  expression
  10.      handler
  11.  
  12. SYNOPSIS
  13.      #include <regexp.h>
  14.  
  15.      regexp *regcomp(exp)
  16.      char *exp;
  17.  
  18.      int regexec(prog, string)
  19.      regexp *prog;
  20.      char *string;
  21.  
  22.      regsub(prog, source, dest)
  23.      regexp *prog;
  24.      char *source;
  25.      char *dest;
  26.  
  27.      regerror(msg)
  28.      char *msg;
  29.  
  30. DESCRIPTION
  31.      These functions implement _e_g_r_e_p(1)-style regular expressions
  32.      and supporting facilities.
  33.  
  34.      _R_e_g_c_o_m_p compiles a regular expression into  a  structure  of
  35.      type  _r_e_g_e_x_p,  and  returns  a pointer to it.  The space has
  36.      been allocated using _m_a_l_l_o_c(3) and may be released by _f_r_e_e.
  37.  
  38.      _R_e_g_e_x_e_c matches a NUL-terminated _s_t_r_i_n_g against the compiled
  39.      regular  expression in _p_r_o_g.  It returns 1 for success and 0
  40.      for failure, and adjusts the contents of _p_r_o_g's  _s_t_a_r_t_p  and
  41.      _e_n_d_p (see below) accordingly.
  42.  
  43.      The members of a _r_e_g_e_x_p structure include at least the  fol-
  44.      lowing (not necessarily in order):
  45.  
  46.           char *startp[NSUBEXP];
  47.           char *endp[NSUBEXP];
  48.  
  49.      where _N_S_U_B_E_X_P is defined (as 10) in the header file.  Once a
  50.      successful  _r_e_g_e_x_e_c  has  been  done  using the _r_e_g_e_x_p, each
  51.      _s_t_a_r_t_p-_e_n_d_p pair describes one substring within the  _s_t_r_i_n_g,
  52.      with  the _s_t_a_r_t_p pointing to the first character of the sub-
  53.      string and the _e_n_d_p pointing to the first character  follow-
  54.      ing  the  substring.   The 0th substring is the substring of
  55.      _s_t_r_i_n_g that matched the whole regular expression.  The  oth-
  56.      ers  are those substrings that matched parenthesized expres-
  57.      sions within  the  regular  expression,  with  parenthesized
  58.      expressions numbered in left-to-right order of their opening
  59.      parentheses.
  60.  
  61.  
  62.  
  63. Sun Release 4.1        Last change: local                       1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. REGEXP(3)              C LIBRARY FUNCTIONS              REGEXP(3)
  71.  
  72.  
  73.  
  74.      _R_e_g_s_u_b copies _s_o_u_r_c_e to _d_e_s_t, making substitutions according
  75.      to  the  most  recent  _r_e_g_e_x_e_c  performed  using _p_r_o_g.  Each
  76.      instance of `&' in _s_o_u_r_c_e is replaced by the substring indi-
  77.      cated  by  _s_t_a_r_t_p[_0]  and  _e_n_d_p[_0].   Each instance of `\_n',
  78.      where _n is a digit, is replaced by the  substring  indicated
  79.      by _s_t_a_r_t_p[_n] and _e_n_d_p[_n].  To get a literal `&' or `\_n' into
  80.      _d_e_s_t, prefix it with `\'; to get a literal `\' preceding `&'
  81.      or `\_n', prefix it with another `\'.
  82.  
  83.      _R_e_g_e_r_r_o_r is called whenever an error is detected in _r_e_g_c_o_m_p,
  84.      _r_e_g_e_x_e_c,  or _r_e_g_s_u_b.  The default _r_e_g_e_r_r_o_r writes the string
  85.      _m_s_g, with a suitable indicator of origin,  on  the  standard
  86.      error  output and invokes _e_x_i_t(2).  _R_e_g_e_r_r_o_r can be replaced
  87.      by the user if other actions are desirable.
  88.  
  89. REGULAR EXPRESSION SYNTAX
  90.      A regular expression is zero or more _b_r_a_n_c_h_e_s, separated  by
  91.      `|'.  It matches anything that matches one of the branches.
  92.  
  93.      A branch is zero or more _p_i_e_c_e_s, concatenated.  It matches a
  94.      match  for  the  first,  followed by a match for the second,
  95.      etc.
  96.  
  97.      A piece is an _a_t_o_m possibly followed by `*',  `+',  or  `?'.
  98.      An  atom  followed  by  `*'  matches a sequence of 0 or more
  99.      matches of the atom.  An atom  followed  by  `+'  matches  a
  100.      sequence of 1 or more matches of the atom.  An atom followed
  101.      by `?' matches a match of the atom, or the null string.
  102.  
  103.      An atom is a regular expression in parentheses  (matching  a
  104.      match  for the regular expression), a _r_a_n_g_e (see below), `.'
  105.      (matching any single  character),  `^'  (matching  the  null
  106.      string  at the beginning of the input string), `$' (matching
  107.      the null string at the end of the input string), a `\'  fol-
  108.      lowed  by a single character (matching that character), or a
  109.      single character with no other significance  (matching  that
  110.      character).
  111.  
  112.      A _r_a_n_g_e is a sequence of characters enclosed  in  `[]'.   It
  113.      normally matches any single character from the sequence.  If
  114.      the sequence begins with `^', it matches any single  charac-
  115.      ter _n_o_t from the rest of the sequence.  If two characters in
  116.      the sequence are separated by `-', this is shorthand for the
  117.      full  list  of  ASCII  characters between them (e.g. `[0-9]'
  118.      matches any decimal digit).  To include a literal `]' in the
  119.      sequence,  make it the first character (following a possible
  120.      `^').  To include a literal `-', make it the first  or  last
  121.      character.
  122.  
  123. AMBIGUITY
  124.      If a regular expression could match two different  parts  of
  125.      the  input  string,  it  will  match  the  one  which begins
  126.  
  127.  
  128.  
  129. Sun Release 4.1        Last change: local                       2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. REGEXP(3)              C LIBRARY FUNCTIONS              REGEXP(3)
  137.  
  138.  
  139.  
  140.      earliest.  If both begin in the same place    but match dif-
  141.      ferent  lengths, or match the same length in different ways,
  142.      life gets messier, as follows.
  143.  
  144.      In general, the possibilities in a list of branches are con-
  145.      sidered  in  left-to-right order, the possibilities for `*',
  146.      `+', and `?' are considered longest-first, nested constructs
  147.      are  considered from the outermost in, and concatenated con-
  148.      structs are considered leftmost-first.  The match that  will
  149.      be  chosen  is the one that uses the earliest possibility in
  150.      the first choice that has to be made.  If there is more than
  151.      one choice, the next will be made in the same manner (earli-
  152.      est possibility)  subject  to  the  decision  on  the  first
  153.      choice.  And so forth.
  154.  
  155.      For example, `(ab|a)b*c' could match `abc'  in  one  of  two
  156.      ways.   The first choice is between `ab' and `a'; since `ab'
  157.      is earlier, and does lead to a successful overall match,  it
  158.      is  chosen.   Since  the `b' is already spoken for, the `b*'
  159.      must match its last possibility-the  empty  string-since  it
  160.      must respect the earlier choice.
  161.  
  162.      In the particular case where no `|'s are present  and  there
  163.      is  only  one  `*',  `+', or `?', the net effect is that the
  164.      longest possible match will be chosen.  So `ab*',  presented
  165.      with  `xabbbby',  will match `abbbb'.  Note that if `ab*' is
  166.      tried against `xabyabbbz', it will  match  `ab'  just  after
  167.      `x', due to the begins-earliest rule.  (In effect, the deci-
  168.      sion on where to start the match is the first choice  to  be
  169.      made,  hence subsequent choices must respect it even if this
  170.      leads them to less-preferred alternatives.)
  171.  
  172. SEE ALSO
  173.      egrep(1), expr(1)
  174.  
  175. DIAGNOSTICS
  176.      _R_e_g_c_o_m_p returns NULL for a  failure  (_r_e_g_e_r_r_o_r  permitting),
  177.      where  failures  are syntax errors, exceeding implementation
  178.      limits, or applying `+' or `*' to a possibly-null operand.
  179.  
  180. HISTORY
  181.      Both code and manual page were written at U of T.  They  are
  182.      intended  to  be  compatible with the Bell V8 _r_e_g_e_x_p(3), but
  183.      are not derived from Bell code.
  184.  
  185. BUGS
  186.      Empty branches and empty regular expressions are  not  port-
  187.      able to V8.
  188.  
  189.      The restriction against applying `*' or `+' to  a  possibly-
  190.      null  operand  is  an artifact of the simplistic implementa-
  191.      tion.
  192.  
  193.  
  194.  
  195. Sun Release 4.1        Last change: local                       3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. REGEXP(3)              C LIBRARY FUNCTIONS              REGEXP(3)
  203.  
  204.  
  205.  
  206.      Does not support _e_g_r_e_p's newline-separated branches; neither
  207.      does the V8 _r_e_g_e_x_p(3), though.
  208.  
  209.      Due to emphasis on  compactness  and  simplicity,  it's  not
  210.      strikingly fast.  It does give special attention to handling
  211.      simple cases quickly.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Sun Release 4.1        Last change: local                       4
  262.  
  263.  
  264.  
  265.